widgetBackground#

The widgetBackground modifier is used to define background styles specifically for widgets, with behavior optimized for iOS 18’s accented (tinted) rendering mode.

Purpose#

In accented mode, iOS displays nearly all view colors—including backgrounds—as white, unless the view is explicitly marked with widgetAccentable. This can cause unintended visual issues in widgets.

The widgetBackground modifier addresses this by:

• Automatically hiding the background when the widget is displayed in accented mode.
• Rendering the background normally in all other display modes (default or full-color).

This ensures your widget layout remains visually consistent and unaffected by system-imposed tinting rules.

Supported Background Variants#

The widgetBackground modifier accepts several input formats:

1. Solid Color (ShapeStyle)#

Apply a simple color to the background.

1<Text widgetBackground="systemBlue">
2  Hello
3</Text>

2. Dynamic Color (DynamicShapeStyle)#

Apply different styles for light and dark modes.

1<Text
2  widgetBackground={{
3    light: "white",
4    dark: "black"
5  }}
6>
7  Mode-aware Background
8</Text>

3. Shape with Fill Style#

Use a shape along with a fill style. This form provides structured and stylized backgrounds.

1<Text
2  widgetBackground={{
3    style: "systemGray6",
4    shape: {
5      type: "rect",
6      cornerRadius: 12,
7      style: "continuous"
8    }
9  }}
10>
11  Rounded Background
12</Text>

You may use any supported built-in or custom shape types, such as:

• 'rect', 'circle', 'capsule', 'ellipse', 'buttonBorder', 'containerRelative'
• Custom rounded rectangles with cornerRadius, cornerSize, or cornerRadii

Behavior in Accented Mode#

• In accented (tinted) mode: The background is automatically hidden to prevent it from rendering as solid white.
• In default and full-color modes: The background displays as defined.

This conditional behavior ensures better design control and visual integrity across widget contexts.

Best Practices#

• Use widgetBackground only in widget-specific views.
• Do not use it for essential visual meaning, since the background may be hidden in accented mode.
• Combine it with widgetAccentable to precisely control which parts of the widget are subject to system tinting.